Added guidelines for using commands in package file. (#61)

Author: samlikins

guidelines/index.md

@@ -77,9 +77,9 @@ This is an array of scripts that will be installed into a project.
   "scripts": ["script.sh"]
 ```
 
-### files
+### files (optional)
 
-This is an array of files that will be installed into a project.
+This is an array of non-script files that will be installed into a project.
 
 ```json
   "files": ["bar.txt", "foo.txt"]
@@ -105,6 +105,23 @@ This is a hash of dependencies only needed during development.  Like the `depend
   }
 ```
 
+### commands (optional)
+
+This is a hash of commands. The keys are the names of the commands and the values are the commands to execute in a shell.  The commands can be called from the command line with `bpkg run` followed by the command name.
+
+```json
+  "commands": {
+    "say-hello": "echo \"Hello $1\""
+  }
+```
+
+The commands are run with `eval`, which runs the command as if on the command line. Commands can contain environment variables, and supports [shell features] (including *[special parameters]* and *[shell expansions]*). Passed parameters (on the command line after the command name) can be accessed in the command by using `$@` or `$1`.
+
+```bash
+$ bpkg run say-hello "Bash Package Manager"
+Hello Bash Package Manager
+```
+
 ## Packaging best practices
 
 These are guidelines that we strongly encourage developers to follow.
@@ -133,3 +150,6 @@ $ my_script some more args --blah
 ```
 
 [json]: http://json.org/example
+[shell features]: https://www.gnu.org/software/bash/manual/html_node/Basic-Shell-Features.html
+[special parameters]: https://www.gnu.org/software/bash/manual/html_node/Special-Parameters.html
+[shell expansions]: https://www.gnu.org/software/bash/manual/html_node/Shell-Expansions.html