craftapps
AGENTS.md8 starsChanged 16 days agoMITView on GitHub
Persistent instructions for any AI agent working in this repository, whatever LLM or tool it runs on. Read this file fully before changing anything. CraftApps — Craft your own apps. A collection of portable AI agent skills that guide a person from discovering a problem in their own life to building, verifying, and (optionally) sharing a small piece of software they own. It is a repository of skills and documentation. It is not an application, hosted service, framework, or orchestration…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository5 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- build-appSkill
- curate-appSkill
- discover-appSkill
- share-appSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
18 rules. About 0 are common, 14 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈14
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 15
Security and privacy first — above every other goal: Never read a user's private conversations directly.
- Distinctive: line 17
Small is beautiful: Prefer the smallest thing that solves the problem.
- Very specific: line 27
Every skill adapts to the user's experience level.
- Distinctive: line 28
Do not build a web app, backend, database, hosted service, multi-agent framework, or publishing automation.
- Very specific: line 62
Define the contract: Every skill states its purpose, when to use it, inputs, outputs, boundaries, and how it hands off — following the …
- Distinctive: line 64
Examples are synthetic: Never derive an example from real user data, even if anonymized.
- Distinctive: line 70
Never send user data to others: no uploads, no third-party services, no telemetry, no sharing between users.
- Very specific: line 79
Generated personal outputs stay out of git: Default output locations (such as craftapps/) are ignored in this repository, and skills that …
- Distinctive: line 83
Write instructions that are specific, testable, and unambiguous.
- Distinctive: line 85
No dependencies, build systems, CI services, package manifests, or frameworks without explicit approval.
- Distinctive: line 89
Update documentation in the same change as the behavior it describes:
- Distinctive: line 96
Write for a mixed audience: developers and people who do not code.
- Distinctive: line 100
Run before finishing any change to skills:
- Distinctive: line 113
Never claim a skill "works" or a change is "tested" without having run these checks.
- Distinctive: line 117
If your agent has general process skills installed (for example Superpowers), use them for work on this repository:
- Very specific: line 121
Before saying a change is finished → verification-before-completion: run the checks in *Testing expectations* and read their output.
- Distinctive: line 129
Do not add orchestration until a real, repeated need is demonstrated and approved.
- Distinctive: line 130
Remove before you add. If a section, file, or option is not needed, delete it.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md 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
AGENTS.md
Persistent instructions for any AI agent working in this repository, whatever LLM or tool it runs on. Read this file fully before changing anything.
What this project is
CraftApps — Craft your own apps. A collection of portable AI agent skills that guide a person from discovering a problem in their own life to building, verifying, and (optionally) sharing a small piece of software they own.
It is a repository of skills and documentation. It is not an application, hosted service, framework, or orchestration engine.
What gets made: native apps (and, when enough, native automations such as scripts or Shortcuts) for the platforms the user already uses — iOS, macOS, Android, Windows, Linux, and so on. Not websites or hosted web services. The platform is chosen from the user's own devices, never assumed. Grown apps use the platform's built-in frameworks; every third-party library, SDK, backend, account, or cross-platform framework needs a stated reason. The same rule applies to this repository itself.
Philosophy (applies to every change)
- Security and privacy first — above every other goal. Never read a user's private conversations directly; never send user data to anyone. When security conflicts with convenience, features, or speed, security wins.
- Own your software. Users control their applications, source code, and data.
- Small is beautiful. Prefer the smallest thing that solves the problem. A shortcut or script beats an app when it is enough.
- Build for yourself first. Software used by one person is still valuable.
- Accessible to everyone. Skills must work for people who have never written code.
- Open and extensible. Skills are plain, readable, customizable text.
- Human agency. AI proposes; the user decides. No consequential action without explicit approval.
Current scope
Implemented: discover-app, build-app (v0), share-app, and curate-app (for the library maintainer). See docs/ROADMAP.md.
- Every skill adapts to the user's experience level; follow
skills/build-app/references/experience-levels.mdas the shared guide. - Do not build a web app, backend, database, hosted service, multi-agent framework, or publishing automation.
Repository map
AGENTS.md This file (agent instructions)
CLAUDE.md One-line pointer to AGENTS.md for tools that only read their own file
README.md Human-facing introduction
.claude-plugin/ Claude Code plugin and marketplace manifests
.codex-plugin/ Codex plugin manifest
.agents/plugins/ Codex marketplace manifest
docs/VISION.md Why the project exists
docs/ARCHITECTURE.md Skill contract, handoff artifacts, planned modules
docs/ROADMAP.md Milestones and status
skills/<skill-name>/ One directory per skill (Agent Skills format)
SKILL.md Entry point: frontmatter + core instructions
references/ Detail loaded on demand (templates, formats, rules)
examples/ Small synthetic examples that ship with the skill
examples/ Synthetic test fixtures with expected findings
scripts/ Local helper scripts (stdlib only, no network)
scripts/validate-skills.sh Structural checks for every skill
scripts/test_*.py Tests for skill scriptsCreating or modifying skills
Skills follow the open Agent Skills format (SKILL.md with YAML frontmatter; see https://agentskills.io/specification).
Rules:
- Directory name =
namefield. Lowercase letters, digits, hyphens. CraftApps skills are named<verb>-app(for examplediscover-app,build-app): what the person wants to do, in their words. Inside a plugin they are also namespaced (craftapps:build-app). - Frontmatter contains
nameanddescription. The description says when to use the skill (triggers, user phrases, situations) in the third person — not a summary of its steps. Keep it under ~500 characters. - Keep
SKILL.mdfocused (well under 500 lines). Move templates, format details, and long rules intoreferences/and link to them by relative path fromSKILL.md. - Stay LLM-neutral and portable. Skills must work with any capable LLM, cloud or local, and never require a specific AI provider, model, or agent product. Describe actions in plain language ("read the file", "ask the user"). Do not depend on tool names, slash commands, or features unique to one agent product in the core instructions. If agent-specific notes are unavoidable, isolate them in a clearly labeled section.
- Define the contract. Every skill states its purpose, when to use it, inputs, outputs, boundaries, and how it hands off — following the skill contract in
docs/ARCHITECTURE.md. - Respect the handoff format. Skills exchange Markdown files with YAML frontmatter (
craftapps_artifact,schema_version, ...). Changing an artifact's structure means bumpingschema_versionand updatingdocs/ARCHITECTURE.md, the template inreferences/, and the examples in the same change. - Examples are synthetic. Never derive an example from real user data, even if anonymized.
- One skill at a time. Finish, validate, and test a skill before starting the next.
Security and privacy requirements (highest priority, non-negotiable)
- Raw conversations never reach the AI. Conversation exports and AI tool session logs are processed only by a local script with no AI and no network (
skills/discover-app/scripts/prepare_input.py). The user reviews and approves the cleaned result before any agent reads it. Agents must not open raw exports or session logs in any way, even to inspect their format. - Never send user data to others: no uploads, no third-party services, no telemetry, no sharing between users.
- Never commit real personal data: conversation exports, chat logs, notes, screenshots, generated reports about a real person, credentials, API keys, tokens, or signing material.
.gitignoreis a safety net, not permission. - Synthetic data only in
examples/,skills/*/examples/, docs, and tests. Mark synthetic files as synthetic. - Skills operate on explicitly provided input only. A skill must never search the user's disk, browser, accounts, or apps for data on its own initiative. It reads the paths the user gives it.
- Local by default. Skills must not send user data to network services, APIs, or the web. If a future skill genuinely needs a network call, it must say exactly what is sent, where, and ask first.
- Be honest about processing. Skills that read personal material must tell the user that a cloud-hosted model sends what it reads to its provider, before reading it.
- Pass only artifacts between skills. A downstream skill reads the handoff artifact, never the user's raw inputs. The user approves artifacts at the checkpoints in
docs/ARCHITECTURE.md. - Minimize and redact. Outputs quote only what is needed as evidence and redact third-party personal details and secrets.
- Generated personal outputs stay out of git. Default output locations (such as
craftapps/) are ignored in this repository, and skills that writecraftapps/inside a person's own repository make it ignored there first.
Quality expectations
- Write instructions that are specific, testable, and unambiguous. Prefer checklists and templates over vague advice.
- Scripts are allowed only when they serve a clear purpose that plain instructions cannot. Use POSIX
shor the Python 3 standard library; no package managers, no third-party packages, no network access. Keep each script small, commented, and runnable from the repo root. - No dependencies, build systems, CI services, package manifests, or frameworks without explicit approval.
Documentation requirements
Update documentation in the same change as the behavior it describes:
README.md— the "What works today" status if capabilities change.docs/ROADMAP.md— milestone status.docs/ARCHITECTURE.md— skill contract, artifacts, or module list changes.- The skill's own
SKILL.md, references, and examples.
Write for a mixed audience: developers and people who do not code. Define jargon on first use.
Testing expectations
Run before finishing any change to skills:
sh scripts/validate-skills.sh
python3 -I scripts/test_prepare_input.pyBehavioral testing for a skill:
- In a fresh agent session, run the skill against a fixture in
examples/(e.g.examples/discovery/synthetic-ios-developer/input/). - Compare the output with that fixture's
expected-findings.mdrubric. - Report the result honestly: which rubric items passed, which failed, and what was not tested.
Never claim a skill "works" or a change is "tested" without having run these checks. State what was verified and what was not.
Process skills for contributors (optional)
If your agent has general process skills installed (for example Superpowers), use them for work on this repository:
- New skill or architecture change →
brainstormingfirst, then ask for approval as above. - Creating or editing any skill →
writing-skills: run a baseline scenario without the change, then with it, and record both in the fixture'sevaluations.md. - Before saying a change is finished →
verification-before-completion: run the checks in Testing expectations and read their output.
Inside the skills themselves, process skills are optional and conditional: each skill says which ones fit in a clearly labeled "Process skills (optional)" section, and CraftApps' rules take precedence. Never make a skill depend on them.
Keep it simple and modular
- Each skill is independently useful. A user may invoke any stage directly with their own input.
- Skills communicate through files, not shared code or a runtime.
- Do not add orchestration until a real, repeated need is demonstrated and approved.
- Remove before you add. If a section, file, or option is not needed, delete it.
Ask for approval before
- Changing the architecture, the skill contract, or the handoff artifact format.
- Adding a new skill, a new top-level directory, or a script.
- Adding any dependency, tool, CI, or infrastructure.
- Changing the license, or adding paid or differently-licensed content. Everything in this repository is MIT and free; never add payment code or license checks.
- Creating repositories, pushing, publishing, or any action visible outside this machine.
Git conventions
- Small, focused commits with imperative subject lines (
Add discovery report template). - Review
git statusand the staged diff before every commit to confirm no personal data, exports, or secrets are included.
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.

